<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<HTML>
<HEAD>
<META name="generator" content="HTML Tidy for Linux/x86 (vers 12 April 2005), see www.w3.org">
<TITLE>CGI environment variables</TITLE>
<META name="GENERATOR" content="Modular DocBook HTML Stylesheet Version 1.79">
<LINK rel="HOME" title="Abyss Web Server For Windows User's Guide" href="index.html">
<LINK rel="UP" title="CGI, FastCGI, and ISAPI" href="scripting.html">
<LINK rel="PREVIOUS" title="How are they run?" href="cgiinternals.html">
<LINK rel="NEXT" title="FastCGI" href="fastcgi.html">
<LINK rel="STYLESHEET" type="text/css" href="stylesheet.css">
<META name="AppleIcon" content="icon.png">
<META name="AppleTitle" content="CGI environment variables">
<META name="Description" content="CGI environment variables">
<META name="AppleOrder" content="">
</HEAD>
<BODY class="SECT1" bgcolor="#FFFFFF" text="#000000">
<DIV class="NAVHEADER">
<TABLE summary="Header navigation table" width="100%" border="0" cellpadding="0" cellspacing="0">
<TR>
<TH colspan="3" align="center">Abyss Web Server For Windows User's Guide</TH>
</TR>
<TR>
<TD width="10%" align="left" valign="bottom"><A href="cgiinternals.html" accesskey="P">Prev</A></TD>
<TD width="80%" align="center" valign="bottom">Chapter 6. CGI, FastCGI, and ISAPI</TD>
<TD width="10%" align="right" valign="bottom"><A href="fastcgi.html" accesskey="N">Next</A></TD>
</TR>
</TABLE>
<HR align="left" width="100%"></DIV>
<DIV class="SECT1">
<H1 class="SECT1"><A name="CGIVARS" id="CGIVARS">CGI environment variables</A></H1>
<P>Before running a CGI application or interpreter, Abyss Web Server sets its environment variables in conformity with the CGI/1.1 specification (as described in <KBD class="USERINPUT"><A href="http://hoohoo.ncsa.uiuc.edu/cgi" target="_top">http://hoohoo.ncsa.uiuc.edu/cgi</A></KBD>) and adds variables declared in the <B class="GUILABEL">Custom Environment Variables</B> table as well as the system environment variables. Some Abyss Web Server specific variables are also set.</P>
<P>The following list contains the variables documented in the CGI/1.1 specification and some variables commonly set by web servers:</P>
<UL>
<LI>
<P><KBD class="USERINPUT">PATH_INFO</KBD>: The extra path information, as given in the requested URL. In fact, scripts can be accessed by their virtual path, followed by extra information at the end of this path. The extra information is sent in <KBD class="USERINPUT">PATH_INFO</KBD>.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">PATH_TRANSLATED</KBD>: The virtual-to-real mapped version of <KBD class="USERINPUT">PATH_INFO</KBD>.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">SCRIPT_NAME</KBD>: The virtual path of the script being executed.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">SCRIPT_FILENAME</KBD> and <KBD class="USERINPUT">REQUEST_FILENAME</KBD>: The real path of the script being executed.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">SCRIPT_URI</KBD>: The full URL to the current object requested by the client.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">URL</KBD>: The full URI of the current request. It is made of the concatenation of <KBD class="USERINPUT">SCRIPT_NAME</KBD> and <KBD class="USERINPUT">PATH_INFO</KBD> (if available.)</P>
</LI>
<LI>
<P><KBD class="USERINPUT">SCRIPT_URL</KBD> and <KBD class="USERINPUT">REQUEST_URI</KBD>: The original request URI sent by the client.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">REQUEST_METHOD</KBD>: The method used by the current request; usually set to <KBD class="USERINPUT">GET</KBD> or <KBD class="USERINPUT">POST</KBD>.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">QUERY_STRING</KBD>: The information which follows the <KBD class="USERINPUT">?</KBD> character in the requested URL.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">CONTENT_TYPE</KBD>: The MIME type of the request body; set only for POST or PUT requests.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">CONTENT_LENGTH</KBD>: The length in bytes of the request body; set only for POST or PUT requests.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">AUTH_TYPE</KBD>: The authentication type if the client has authenticated itself to access the script.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">AUTH_USER</KBD> and <KBD class="USERINPUT">REMOTE_USER</KBD>: The name of the user as issued by the client when authenticating itself to access the script.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">ALL_HTTP</KBD>: All HTTP headers sent by the client. Headers are separated by carriage return characters (ASCII 13 - <KBD class="USERINPUT">\n</KBD>) and each header name is prefixed by <KBD class="USERINPUT">HTTP_</KBD>, transformed to upper cases, and <KBD class="USERINPUT">-</KBD> characters it contains are replaced by <KBD class="USERINPUT">_</KBD> characters.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">ALL_RAW</KBD>: All HTTP headers as sent by the client in raw form. No transformation on the header names is applied.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">SERVER_SOFTWARE</KBD>: The web server's software identity.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">SERVER_NAME</KBD>: The host name or the IP address of the computer running the web server as given in the requested URL.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">SERVER_PORT</KBD>: The port to which the request was sent.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">GATEWAY_INTERFACE</KBD>: The CGI Specification version supported by the web server; always set to <KBD class="USERINPUT">CGI/1.1</KBD>.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">SERVER_PROTOCOL</KBD>: The HTTP protocol version used by the current request.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">REMOTE_ADDR</KBD>: The IP address of the computer that sent the request.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">REMOTE_PORT</KBD>: The port from which the request was sent.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">DOCUMENT_ROOT</KBD>: The absolute path of the web site files. It has the same value as <B class="GUILABEL">Documents Path</B>.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">INSTANCE_ID</KBD>: The numerical identifier of the host which served the request. On Abyss Web Server X1, it is always set to 1 since there is only a single host.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">APPL_MD_PATH</KBD>: The virtual path of the deepest alias which contains the request URI. If no alias contains the request URI, the variable is set to <KBD class="USERINPUT">/</KBD>.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">APPL_PHYSICAL_PATH</KBD>: The real path of the deepest alias which contains the request URI. If no alias contains the request URI, the variable is set to the same value as <KBD class="USERINPUT">DOCUMENT_ROOT</KBD>.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">IS_SUBREQ</KBD>: It is set to <KBD class="USERINPUT">true</KBD> if the current request is a subrequest, i.e. a request not directly invoked by a client. Otherwise, it is set to <KBD class="USERINPUT">true</KBD>. Subrequests are generated by the server for internal processing. XSSI includes for example result in subrequests.</P>
</LI>
</UL>
<P>If the current request is served by an SSL enabled host, the following SSL related variables are also available:</P>
<UL>
<LI>
<P><KBD class="USERINPUT">SSL_PROTOCOL</KBD>: The SSL protocol version. It could be <KBD class="USERINPUT">SSLv2</KBD>, <KBD class="USERINPUT">SSLv3</KBD>, or <KBD class="USERINPUT">TLSv1</KBD>.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">SSL_CIPHER</KBD> and <KBD class="USERINPUT">HTTPS_CIPHER</KBD>: The SSL protocol version. It could be <KBD class="USERINPUT">SSLv2</KBD>, <KBD class="USERINPUT">SSLv3</KBD>, or <KBD class="USERINPUT">TLSv1</KBD>.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">SSL_CIPHER_EXPORT</KBD>: It is set to <KBD class="USERINPUT">true</KBD> if the cipher is conforming to US export restrictions (i.e. it is limited to 56 bit symmetric keys and 1024 asymmetric keys).</P>
</LI>
<LI>
<P><KBD class="USERINPUT">SSL_CIPHER_USEKEYSIZE</KBD> and <KBD class="USERINPUT">HTTPS_SECRETKEYSIZE</KBD>: The number of cipher bits currently used.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">SSL_CIPHER_ALGKEYSIZE</KBD> and <KBD class="USERINPUT">HTTPS_KEYSIZE</KBD>: The maximum number of cipher bits that could be used.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">SSL_SERVER_M_VERSION</KBD>: The version of the server's certificate.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">SSL_SERVER_M_SERIAL</KBD>: The serial number of the server's certificate.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">SSL_SERVER_V_START</KBD>: The date corresponding to the start of the validity the server's certificate.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">SSL_SERVER_V_END</KBD>: The date corresponding to the end of the validity the server's certificate.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">SSL_SERVER_A_SIG</KBD>: The algorithm used to sign the server's certificate.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">SSL_SERVER_A_KEY</KBD>: The encryption type of the private key of the server's certificate.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">SSL_SERVER_S_DN</KBD> and <KBD class="USERINPUT">HTTPS_SERVER_SUBJECT</KBD>: The value of the subject's DN (distinguished name) of the server's certificate.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">SSL_SERVER_S_DN_</KBD><SPAN class="emphasis"><I class="EMPHASIS">component</I></SPAN>: The value of the <SPAN class="emphasis"><I class="EMPHASIS">component</I></SPAN> of the subject's DN (distinguished name) of the server's certificate. <SPAN class="emphasis"><I class="EMPHASIS">component</I></SPAN> can be <KBD class="USERINPUT">CN</KBD> (Common Name), <KBD class="USERINPUT">C</KBD> (Country), <KBD class="USERINPUT">ST</KBD> or <KBD class="USERINPUT">SP</KBD> (State/Province), <KBD class="USERINPUT">L</KBD> (Locality), <KBD class="USERINPUT">O</KBD> (Organization), <KBD class="USERINPUT">OU</KBD> (Organization Unit), <KBD class="USERINPUT">T</KBD> (Title), <KBD class="USERINPUT">I</KBD> (Initials), <KBD class="USERINPUT">G</KBD> (Given Name), <KBD class="USERINPUT">S</KBD> (Surname), <KBD class="USERINPUT">D</KBD> (Description), <KBD class="USERINPUT">Email</KBD> (Contact Email).</P>
</LI>
<LI>
<P><KBD class="USERINPUT">SSL_SERVER_I_DN</KBD> and <KBD class="USERINPUT">HTTPS_SERVER_ISSUER</KBD>: The value of the issuer's DN (distinguished name) of the server's certificate.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">SSL_SERVER_I_DN_</KBD><SPAN class="emphasis"><I class="EMPHASIS">component</I></SPAN>: The value of the <SPAN class="emphasis"><I class="EMPHASIS">component</I></SPAN> of the issuer's DN (distinguished name) of the server's certificate.</P>
</LI>
</UL>
<P>The Abyss Web Server specific variables provide a means to access to server and host statistics. They are listed below:</P>
<UL>
<LI>
<P><KBD class="USERINPUT">X_ABYSS_STATS_SERVER_UPTIME</KBD>: The total time in seconds during which the server was up.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">X_ABYSS_STATS_SERVER_CURRENT_UPTIME</KBD>: The total time in seconds during which the server was up since the last start or restart.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">X_ABYSS_STATS_SERVER_TOTAL</KBD>: The total number of processed requests for all the hosts. It includes also bad requests that were not targeting a specific host and that resulted in an error.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">X_ABYSS_STATS_SERVER_ERROR</KBD>: The number of requests for which the server replied by an error.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">X_ABYSS_STATS_SERVER_HTML</KBD>: The number of requests the server replied to by a document which MIME type was <KBD class="USERINPUT">text/html</KBD>.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">X_ABYSS_STATS_SERVER_IMAGE</KBD>: The number of requests the server replied to by a document which MIME type starts with <KBD class="USERINPUT">image/</KBD>.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">X_ABYSS_STATS_SERVER_NOTMODIFIED</KBD>: The number of requests for which the server detected that the requested document has not changed.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">X_ABYSS_STATS_SERVER_OUTPUT</KBD>: The total size in bytes of the payload sent by the server to the clients.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">X_ABYSS_STATS_SERVER_COMPRESS_TOTAL</KBD>: The total number of compressed responses for all the hosts.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">X_ABYSS_STATS_SERVER_COMPRESS_OUTPUT_TOTAL</KBD>: The total size in bytes of the payload sent by the server to the clients in compressed responses.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">X_ABYSS_STATS_SERVER_COMPRESS_ORIGINAL_OUTPUT</KBD>: The total original uncompressed size in bytes of the payload sent by the server to the clients in compressed responses.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">X_ABYSS_STATS_HOST_UPTIME</KBD>: The total time in seconds during which the current host was up.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">X_ABYSS_STATS_HOST_CURRENT_UPTIME</KBD>: The time in seconds during which the current host was up since the last server start or restart.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">X_ABYSS_STATS_HOST_TOTAL</KBD>: The total number of requests processed by the current host.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">X_ABYSS_STATS_HOST_ERROR</KBD>: The number of requests targeting the current host that resulted in an error.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">X_ABYSS_STATS_HOST_HTML</KBD>: The number of requests the current host replied to by a document which MIME type was <KBD class="USERINPUT">text/html</KBD>.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">X_ABYSS_STATS_HOST_IMAGE</KBD>: The number of requests the current host replied to by a document which MIME type starts with <KBD class="USERINPUT">image/</KBD>.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">X_ABYSS_STATS_HOST_NOTMODIFIED</KBD>: The number of requests for which the current host detected that the requested document has not changed.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">X_ABYSS_STATS_HOST_OUTPUT</KBD>: The total size in bytes of the payload sent by the current host to the clients.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">X_ABYSS_STATS_HOST_COMPRESS_TOTAL</KBD>: The total number of compressed responses for the current host.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">X_ABYSS_STATS_HOST_COMPRESS_OUTPUT_TOTAL</KBD>: The total size in bytes of the payload sent by the current host to the clients in compressed responses.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">X_ABYSS_STATS_HOST_COMPRESS_ORIGINAL_OUTPUT</KBD>: The total original uncompressed size in bytes of the payload sent by the current host to the clients in compressed responses.</P>
</LI>
</UL>
<P>In addition to these variables, all header lines received in the request are added to the environment with the prefix <KBD class="USERINPUT">HTTP_</KBD> followed by the header name in upper cases. All <KBD class="USERINPUT">-</KBD> characters in the header name are changed to underscore <KBD class="USERINPUT">_</KBD> characters. For example, <KBD class="USERINPUT">User-Agent</KBD> is translated to <KBD class="USERINPUT">HTTP_USER_AGENT</KBD>.</P>
<P>If the request results from an internal redirection (from an XSSI document or if it is used as a custom error page for example), the environment variables of the parent request are also added and each variable name is prefixed by <KBD class="USERINPUT">REDIRECT_</KBD>. The parent request's status code is stored in the special variables <KBD class="USERINPUT">REDIRECT_STATUS</KBD> and <KBD class="USERINPUT">REDIRECT_STATUS_CODE</KBD>. The cookies of the parent request are also passed to the redirected request in the <KBD class="USERINPUT">COOKIES</KBD> environment variable. <KBD class="USERINPUT">REDIRECT_STATUS_CODE</KBD> may seem redundant but it is actually useful when with PHP scripts as some PHP configurations require setting <KBD class="USERINPUT">REDIRECT_STATUS</KBD> to a fixed value.</P>
<DIV class="EXAMPLE"><A name="AEN2088" id="AEN2088"></A>
<P><B>Example 6-1. Using the redirection information in scripts</B></P>
<P>If a script is invoked after an internal redirection, it can retrieve some interesting information from the environment about its parent request such as:</P>
<UL>
<LI>
<P><KBD class="USERINPUT">REDIRECT_SCRIPT_NAME</KBD>: The virtual path of the parent document.</P>
</LI>
<LI>
<P><KBD class="USERINPUT">REDIRECT_STATUS_CODE</KBD>: The status code of the parent request. It is useful when writing scripts that generate custom error pages.</P>
</LI>
</UL>
</DIV>
<DIV class="NOTE">
<BLOCKQUOTE class="NOTE">
<P><B>Note:</B> The CGI environment variables are not only useful for CGI applications and interpreters. They are also available and used in XSSI pages and ISAPI interpreters and applications.</P>
</BLOCKQUOTE>
</DIV>
</DIV>
<DIV class="NAVFOOTER">
<HR align="left" width="100%">
<TABLE summary="Footer navigation table" width="100%" border="0" cellpadding="0" cellspacing="0">
<TR>
<TD width="33%" align="left" valign="top"><A href="cgiinternals.html" accesskey="P">Prev</A></TD>
<TD width="34%" align="center" valign="top"><A href="index.html" accesskey="H">Home</A></TD>
<TD width="33%" align="right" valign="top"><A href="fastcgi.html" accesskey="N">Next</A></TD>
</TR>
<TR>
<TD width="33%" align="left" valign="top">How are they run?</TD>
<TD width="34%" align="center" valign="top"><A href="scripting.html" accesskey="U">Up</A></TD>
<TD width="33%" align="right" valign="top">FastCGI</TD>
</TR>
</TABLE>
</DIV>
<DIV class="COPYRIGHT">Copyright &copy; 2001-2009 Aprelium</DIV>
</BODY>
</HTML>
